home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / DevCon / Milan_1991 / Devcon91.3 / Debug / devel / autodoc.style < prev    next >
Encoding:
Text File  |  1992-09-01  |  9.2 KB  |  297 lines
  1. ----------------------------------------------------------------------------
  2. Autodoc style guide - June 1990
  3. ----------------------------------------------------------------------------
  4.  
  5. Autodocs are part of each source module.
  6.  
  7. Autodoc looks at the start of each line, and considers a match of the
  8. pattern "/****** " or "******* " as the start of an autodoc (* or /, 6
  9. asterisks, then a space).  An autodoc ends with at least three asterisks at 
  10. the start of a line ("***").  If the start string is "/****i* " the autodoc is
  11. "internal", and will be extracted only if the "internal" flag of autodoc is
  12. enabled (this does not work yet).
  13.  
  14. Please look at your autodoc output to see if it has problems before
  15. releasing.
  16.  
  17.  
  18. Here is a sample "correct" autodoc:
  19.  
  20.  
  21. /****** financial.library/StealMoney ******************************************
  22. * 
  23. *   NAME    
  24. *     StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  25. * 
  26. *   SYNOPSIS
  27. *    error = StealMoney( userName,amount,destAccount,falseTrail )
  28. *    D0,Z                D0       D1.W    A0         [A1]
  29. *
  30. *    BYTE StealMoney
  31. *         ( STRPTR,UWORD,struct AccountSpec *,struct falseTrail *);
  32. *
  33. *   FUNCTION
  34. *    Transfer money from the Federal Reserve Bank into the specified
  35. *    interest-earning checking account.  No records of the transaction
  36. *    will be retained.
  37. * 
  38. *   INPUTS
  39. *     userName      - name to make the transaction under.  Popular favorites
  40. *                    include "Ronald Reagan" and "Mohamar Quadaffi".
  41. *    amount        - Number of dollars to transfer (in thousands).
  42. *    destAccount   - A filled-in AccountSpec structure detailing the
  43. *                    destination account (see financial/accounts.h).
  44. *            If NULL, a second Great Depression will be triggered.
  45. *    falseTrail    - If the DA_FALSETRAIL bit is set in the destAccount,
  46. *            a falseTrail structure must be provided.
  47. *    
  48. *   RESULT
  49. *     error - zero for success, else an error code is returned (see
  50. *            financial/errors.h).  The Z condition code is guaranteed.
  51. * 
  52. *   EXAMPLE
  53. *    Federal regulations prohibit a demonstration of this function. 
  54. *
  55. *   NOTES
  56. *    Do not run on Tuesdays!
  57. *
  58. *   BUGS
  59. *     Before V88, this function would occasionally print the address and
  60. *    home phone number of the caller on local police 976 terminals.
  61. *    We are confident that this problem has been resolved.
  62. * 
  63. *   SEE ALSO
  64. *     CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  65. *    financial/misc.h
  66. * 
  67. ******************************************************************************
  68. *
  69. *     Private notes:
  70. *        A4=stringbean
  71. *        A3=dogbreath
  72. *    Must preserve A1 for taxshelter.library
  73. */
  74.  
  75. A "blank" version of this autodoc is provided at the end of this file.
  76. There are three spaces from the * to the start of each HEADING.  There
  77. is one tab after the * before the start of the body text.  No other tabs
  78. are used.
  79.  
  80.  
  81. ------------------ general style notes -----------------------------------
  82.  
  83. It is critical that changes be noted in a sane manner.
  84.  
  85. When referring to a function, the standard format is FunctionName().
  86.  
  87.  
  88. Capitalization should be correct.  Here are some guidelines:
  89.  
  90.     1> The words Amiga, Exec, Workbench, Autoconfig, AmigaDOS, Kickstart,
  91.        Commodore, Commodore-Amiga, etc.  all are trademarks, and *must*
  92.        be capitalized.
  93.  
  94.     2> Names of "things" are as defined.  For example, "OpenWindow()",
  95.        and "a Window structure".  "fiddles with your window" does not
  96.        refer to the structure, and should not be capitalized.
  97.  
  98.  
  99. Lines terminate at column 77, so the autodocs are readable from within
  100. an Amiga CLI window.
  101.  
  102.  
  103. ------------------ heading-by-heading description ------------------------
  104.  
  105.  
  106. ---------------------------------
  107. ******* modulename.type/FunctionName *************************************
  108. ---------------------------------
  109.  
  110.     GOOD
  111.         exec.library/AddTail
  112.         math<various>.library/Function
  113.         audio.device/CD_ASKDEFAULTKEYMAP
  114.     
  115.     BAD
  116.         Library/Translator/Routine
  117.         Routine
  118.         Resources/Misc/Routine
  119.         audio.device/AskKeyMap
  120.  
  121. Before the / is the module name (as the caller sees it).  After the / is the
  122. function or command name (as the caller sees it).  For devices this is the all
  123. caps command placed into IO_COMMAND.  The special function name
  124. "--background--" may be used for background information common to many
  125. functions.
  126.  
  127.  
  128. /*
  129. ******* zip.zoop/Zum **************
  130.  
  131. Is an alternate form.
  132.  
  133.  
  134. ---------------------------------
  135. *   NAME    
  136. *     StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  137. ---------------------------------
  138. Put YourFunctionName, " -- ", then a ONE LINE description of what it does.
  139. Real sentences with periods are preferred.
  140.  
  141.  
  142. ---------------------------------
  143. SYNOPSIS
  144. ---------------------------------
  145.  
  146. The SYNOPSIS has three parts.  The C calling convention, the
  147. assembly registers, and (new) the function prototype.
  148.  
  149. Do NOT indicate that the library base goes in A6, unless there is
  150. something special about your module.  If parts of a register are
  151. ignored, note that next to the register number.  The standard form
  152. is the register number followed by the number of bits (D0:16).  *Only
  153. specify this if the upper bits are, and always will be, ignored*.
  154.  
  155. An ANSI standard prototype is a new addition to our specification.
  156. This must be a ready-to-compile indication of the function's types.
  157. Do *not* use the base types, use the "types.h" file.  This line must compile!
  158.  
  159.  
  160. Base type          Use these typedefs            notes
  161. ----------------------------------------------------------------------------
  162. --untyped pointer--    void *       [  void *AllocMem( ULONG,ULONG );       ]
  163. --no parameter/return--    void       [  void RemakeDisplay(void);            ]
  164. --function pointer--    ???       [  (unresolved issue)                   ]
  165.  
  166. unsigned char *        STRPTR       [ "char *" is -not- acceptable!!        ]
  167. short            WORD
  168. unsigned short        UWORD
  169. unsigned short *    UWORD *    [  word aligned pointer]
  170. unsigned long *        ULONG *    [  word aligned pointer to ULONG object ]
  171.             BPTR       [  Our old friend               ]
  172.  
  173.  
  174. There is one line where you name the parameters and return values,
  175. another where you do the registers, and a third with the prototype
  176. that replaces the UNIX style type declarations that some few modules used
  177. (intuition mostly).  So, you can still refer to parameters and return
  178. values by name in the description.
  179.  
  180. old-style:
  181.     RealPos = RemoveGadget( Window, Gadgets, Pos )
  182.       D0              A0      A1      D0
  183.     
  184.     UWORD    RealPos;
  185.     struct Window    *Window;
  186.     struct Gadget    *Gadgets;
  187.     UWORD        POS;
  188.  
  189. becomes:
  190.     RealPos = RemoveGadget( Window, Gadgets, Pos )
  191.       D0              A0      A1      D0
  192.     UWORD RemoveGadget( struct Window *, struct Gadgets *, UWORD );
  193.  
  194.  
  195. If any of these lines are too long, exert your individuality and word-wrap
  196. it! 
  197.  
  198.  
  199. ---------------------------------
  200. FUNCTION
  201. ---------------------------------
  202.  
  203.     !describe WHAT your function does in generally accepted English,
  204.     !keep jargon to a minimum, but don't sacrifice clarity and accuracy.
  205.     !You may even take the radical step of using a spelling checker. Nah.
  206.  
  207. ---------------------------------
  208. INPUTS
  209. ---------------------------------
  210. Describe the range and domain of each input parameter.  Use the same
  211. name token used in the first SYNOPSIS line (so the user can match inputs
  212. to the descriptions).  The preferred follower is "-". (See example)
  213. Don't forget to note the actions taken for NULL pointers!.
  214.  
  215. The suggestion has been made to standardize on:
  216.  
  217.     TheToken - If the description is long, then indent the second line
  218.         by 4 spaces.  Many modules currently use whatever number of spaces
  219.         looks good.
  220.  
  221.  
  222. ---------------------------------
  223. RESULT
  224. ---------------------------------
  225. Describe the range and domain of each output.
  226. Describe which abnormal conditions produce each error output.
  227.  
  228.  
  229. ---------------------------------
  230. EXAMPLE
  231. ---------------------------------
  232. An optional *short* example of how your function is called.  This must BE
  233. TESTED.  Write, test, then remove lines if needed to shorten the example.
  234. Use "..." to indicate removed sections.  Do not edit the example after
  235. creation (unless you retest).
  236.  
  237. | Sadly some compilers do not allow nested C comments.  Instead we will
  238. | reverse the \, and have autodoc magically fix things up.
  239.  
  240.     \* write this in your autodoc *\
  241.     /* and autodoc will convert to the standard form */
  242.  
  243. | Be sure to search old source code created prior to this new definition!
  244.  
  245. ---------------------------------
  246. NOTES
  247. ---------------------------------
  248.     Helpful hints, warnings, tricks, traps, etc. (optional)
  249.  
  250.  
  251. ---------------------------------
  252. BUGS
  253. ---------------------------------
  254.     !if there are any, describe the bug, and how it can be avoided.
  255.     List versions, workarounds, etc.
  256.  
  257. ---------------------------------
  258. SEE ALSO
  259. ---------------------------------
  260.     If there are other functions which help describe the data structures,
  261.     or are otherwise related to this function, place their names here.
  262.     Note include files, where appropriate (it is acceptable to list
  263.     just the ".h" file, an assume the assembly user will find the ".i".)
  264.  
  265.     Functions in THIS module are simply listed, with () to indicate they
  266.     are a function.  Functions from OTHER modules are preceded by the
  267.     module name.  (See the StealMoney() autodoc for examples).
  268.  
  269.  
  270. NOTE: See autodoc.sample for other templates
  271.  
  272.  
  273. /****** / ******************************************
  274. *
  275. *   NAME    
  276. *
  277. *   SYNOPSIS
  278. *
  279. *   FUNCTION
  280. *
  281. *   INPUTS
  282. *
  283. *   RESULT
  284. *
  285. *   EXAMPLE
  286. *
  287. *   NOTES
  288. *
  289. *   BUGS
  290. *
  291. *   SEE ALSO
  292. *
  293. ******************************************************************************
  294. *
  295. */
  296.  
  297.